Costing Value Builtins with Worst-Case Benchmarking

Overview

This PR implements costing for four Plutus Core Value builtins: LookupCoin, ValueContains, ValueData, and UnValueData. The implementation uses a worst-case oriented benchmarking strategy that ensures conservative cost estimates for adversarial on-chain scenarios.

Values in Plutus Core are implemented as nested Maps: Map PolicyId (Map TokenName Quantity), backed by BST-based Data.Map. The benchmarking approach systematically explores BST worst-case behavior through careful test case generation.

Cost Models by Builtin

LookupCoin

Cost Model Type: linear_in_z (linear in sum of logarithms)

• CPU: intercept + slope × (log(outerSize) + log(maxInnerSize))
• Memory: constant (1 word)

Size Measure: ValueLogOuterSizeAddLogMaxInnerSize

• Computes log₂(numPolicies) + log₂(maxTokensPerPolicy)
• Reflects O(log m + log k) BST lookup cost through nested maps
• Based on experimental evidence showing lookup time scales with sum of depths, not their maximum

Rationale: Looking up a coin requires traversing the outer BST to find the policy, then traversing the largest inner BST to find the token. The sum of logarithms accurately models the total comparison cost.

ValueContains

Cost Model Type: multiplied_sizes (product of dimensions)

• CPU: intercept + slope × container_log_size × contained_total_entries
• Memory: constant (1 word)

Size Measures:

• Container: ValueLogOuterSizeAddLogMaxInnerSize (same as LookupCoin)
• Contained: ValueTotalSize (total number of entries)

Rationale: ValueContains performs one LookupCoin operation per entry in the contained Value. The cost is the product of:

1. Per-lookup cost (proportional to container BST depth: log m + log k)
2. Number of lookups (contained Value size: n₂)

Result: O(n₂ × (log m₁ + log k₁)) complexity.

Implementation Note: Uses Map.isSubmapOfBy with optimized short-circuiting, providing 2-4x speedup over naive iteration.

ValueData

Cost Model Type: constant_cost

• CPU: constant (194,713 steps)
• Memory: constant (1 word)

Size Measure: Raw Value (no wrapper needed)

Rationale: Wrapping a Value as Plutus Data is a constant-time pointer operation. The Data structure already exists in memory; valueData just changes the type tag. Benchmarks confirm minimal variance across Value sizes.

UnValueData

Cost Model Type: linear_in_x (linear in Data size)

• CPU: intercept + slope × data_size
• Memory: constant (1 word)

Size Measure: Standard Data size (built-in)

Rationale: Deserializing Data to Value requires traversing the Data structure and validating the nested map structure. Cost scales linearly with Data size. The slope (43,200 steps per Data node) reflects validation overhead.

ExMemoryUsage Newtypes: Size Measure Logic

ValueLogOuterSizeAddLogMaxInnerSize

instance ExMemoryUsage ValueLogOuterSizeAddLogMaxInnerSize where
    memoryUsage (ValueLogOuterSizeAddLogMaxInnerSize v) =
      let outerSize = Map.size (Value.unpack v)          -- number of policies
          innerSize = Value.maxInnerSize v                -- max tokens in any policy
          logOuter = if outerSize > 0 then integerLog2 outerSize + 1 else 0
          logInner = if innerSize > 0 then integerLog2 innerSize + 1 else 0
      in singletonRose $ fromIntegral (logOuter + logInner)

Purpose: Models worst-case BST traversal depth through nested maps.

Key Insight: For a Value with m policies where the largest policy has k tokens, worst-case lookup requires:

• Traversing outer BST of depth ~log₂(m)
• Traversing largest inner BST of depth ~log₂(k)
• Total comparisons: proportional to log m + log k

Why sum, not max?: Experimental benchmarks showed lookup time scales linearly with the sum of depths. Both traversals must complete; they're not alternatives.

ValueTotalSize

instance ExMemoryUsage ValueTotalSize where
    memoryUsage = singletonRose . fromIntegral . Value.totalSize . unValueTotalSize

Purpose: Counts total number of (policyId, tokenName, quantity) entries across all policies.

Usage: Measures iteration count for operations like ValueContains that must check every entry in the contained Value.

Worst-Case Benchmarking Strategy

The benchmarking methodology prioritizes conservative cost estimates through systematic worst-case generation.

1. Worst-Case BST Keys

Problem: Random ByteString keys typically differ in the first 1-2 bytes, making BST comparisons artificially cheap (short-circuit after 1-2 byte comparisons).

Solution: Generate keys with a common prefix:

generateKey = do
  let prefix = BS.replicate 28 0xFF        -- 28 bytes of 0xFF
  suffix <- BS.pack <$> replicateM 4 (uniformRM (0, 255))
  return (prefix <> suffix)                 -- 32-byte key

Result: Forces full 32-byte comparisons during BST traversal, reflecting adversarial scenarios where an attacker crafts keys to maximize comparison cost.

2. Power-of-2 Size Grid

Approach: Test all combinations of sizes from the sequence:

2, 3, 4, 6, 8, 11, 16, 23, 32, 45, 64, 91, 128, 181, 256, 362, 512, 724, 1024, 1448

This sequence includes both powers of 2 (2ⁿ) and geometric means (2^(n+0.5) ≈ 2ⁿ × √2).

Coverage:

• LookupCoin: 20 × 20 = 400 test points spanning BST depths 2 to 21
• ValueContains: 10 × 10 = 100 container configurations, each tested with 10 contained sizes

Rationale: Power-of-2 sizing systematically explores different BST depths. The half-powers provide finer granularity between powers, ensuring no "gaps" in depth coverage.

3. Maximum Depth Targeting

For each Value generated, we track the deepest entry (rightmost in both outer and inner BSTs):

generateConstrainedValueWithMaxPolicy numPolicies tokensPerPolicy = do
  policyIds <- replicateM numPolicies (generateKey g)
  tokenNames <- replicateM tokensPerPolicy (generateKey g)

  let sortedPolicyIds = sort policyIds
      sortedTokenNames = sort tokenNames
      maxPolicyId = last sortedPolicyIds      -- deepest in outer BST
      deepestToken = last sortedTokenNames    -- deepest in inner BST

  -- Structure: max policy gets ALL tokens, others get minimal (1 token each)
  pure (value, maxPolicyId, deepestToken)

Key Optimization: Only the max policy receives all tokens. Other policies get a single token each. This minimizes "off-path" costs while maximizing depth at the target lookup location.

Lookup Keys: Benchmarks always query (maxPolicyId, deepestToken), forcing maximum BST traversal depth.

Benchmark Generation by Builtin

LookupCoin: Exhaustive Depth Coverage

lookupCoinArgs =
  [ (maxPolicyId, deepestToken, value)
  | numPolicies <- [2, 3, 4, ..., 1024, 1448]      -- 20 sizes
  , tokensPerPolicy <- [2, 3, 4, ..., 1024, 1448]   -- 20 sizes
  ]

Result: 400 test points systematically covering all depth combinations from (2,2) to (21,21).

Lookup Strategy: Every benchmark queries the deepest possible entry in the Value's BST structure.

ValueContains: Subset with Worst-Case Entry

valueContainsArgs =
  [ (container, contained)
  | numPolicies <- [2, 4, 8, ..., 512, 1024]       -- 10 sizes
  , tokensPerPolicy <- [2, 4, 8, ..., 512, 1024]   -- 10 sizes
  , containedSize <- [step, 2*step, ..., min(1000, totalEntries)]  -- 10 sizes
  ]

Contained Value Construction:

1. Generate container with worst-case BST structure
2. Extract all entries as flat list
3. Select containedSize - 1 arbitrary entries
4. Append the deepest entry last

Critical Detail: Placing the deepest entry last ensures:

• All lookups succeed (no early exit from subset check)
• Maximum BST depth is traversed for at least one lookup
• Tests realistic "contained ⊆ container" relationships

Result: ~1000 systematic test cases exploring both container depth and iteration count dimensions.

ValueData & UnValueData: Random Distribution

generateTestValues = empty : replicateM 100 (randomValue 1 to 100_000 entries)

Strategy: Random sampling with uniform distribution across:

• Number of policies (1 to numEntries)
• Tokens per policy (distributed to reach numEntries total)
• Entry counts from 1 to 100,000

Maximum Size: 100,000 entries (up from original 416), reflecting execution budget constraints rather than ledger storage limits.

Rationale: Scripts can programmatically generate Values much larger than on-chain storage allows. The 100K limit represents what's achievable within maximum CPU execution budget (~10-15 billion picoseconds) while leaving room for actual script logic.

Constant vs Linear Models: ValueData shows constant cost (pointer wrapping), while UnValueData shows linear cost (structural validation), confirmed by benchmarks across this wide size range.

Performance Impact

The valueContains implementation received a 2-4x speedup optimization:

Before: Manual iteration with early exit

valueContains v1 v2 = all (\(p,t,q) -> lookupCoin p t v1 >= q) (toList v2)

After: Native Map.isSubmapOfBy

valueContains v1 v2 = Map.isSubmapOfBy (Map.isSubmapOfBy (<=)) (unpack v2) (unpack v1)

Benefit: Leverages optimized Map internals with better short-circuiting and comparison batching. Cost model updated to reflect improved performance.

Testing & Validation

• Conformance tests: Updated budget expectations across 100+ test cases
• Ledger API tests: Verified backward compatibility with existing script validation
• Benchmark data: 400+ data points per builtin ensuring robust cost model fitting
• Cost model validation: R² > 0.95 for all fitted models

Visualization

Interactive cost model visualizations available at:
https://plutus.cardano.intersectmbo.org/cost-models/

To preview this PR's cost models, configure the data source to load from this branch:

1. Open the visualization page for the function (e.g., /cost-models/valuecontains/)
2. Update the data source URLs to point to this branch's raw files:
   • Benchmark data: https://raw.githubusercontent.com/IntersectMBO/plutus/yura/costing-builtin-value/plutus-core/cost-model/data/benching-conway.csv
   • Cost model: https://raw.githubusercontent.com/IntersectMBO/plutus/yura/costing-builtin-value/plutus-core/cost-model/data/builtinCostModelC.json
3. The visualization will render this PR's updated cost model parameters

Available visualizations: lookupCoin, valueContains, valueData, unValueData

Summary

This PR establishes production-ready costing for Value builtins through:

1. Accurate cost models based on algorithmic complexity (BST depth, iteration count)
2. Worst-case oriented benchmarking ensuring conservative estimates for adversarial scenarios
3. Systematic test coverage across realistic and extreme Value sizes
4. Performance optimization (valueContains 2-4x speedup) reflected in updated costs

The worst-case focus—common-prefix keys, maximum-depth lookups, systematic size coverage—provides strong safety guarantees for on-chain execution budgeting.